//
//  DMThinkingManager.h
//  DualMediationSDK
//
//  Created by YeJary on 2025/8/7.
//

#import <Foundation/Foundation.h>

NS_ASSUME_NONNULL_BEGIN

/**
 * @brief ThinkingData数据分析管理器
 *
 * DMThinkingManager是一个单例类，负责集成和管理ThinkingData数据分析SDK的功能。
 * 主要职责包括：
 * - 配置和初始化ThinkingData SDK
 * - 管理用户属性和公共属性
 * - 追踪自定义事件和游戏关卡事件
 * - 提供统一的数据分析接口
 *
 * @note 该类采用单例模式，通过shareThinkingManager方法获取实例
 *
 * @example
 * ```objc
 * // 获取管理器实例
 * DMThinkingManager *manager = [DMThinkingManager shareThinkingManager];
 *
 * // 配置SDK
 * [manager thinkingConfig];
 *
 * // 追踪事件
 * [manager thinkingTrackEventWithKey:@"button_click" jsonStr:@{@"button_name": @"login"}];
 * ```
 */
@interface DMThinkingManager : NSObject

#pragma mark - 单例管理

/**
 * @brief 获取DMThinkingManager单例实例
 *
 * @return DMThinkingManager的单例实例
 *
 * @note 该方法是线程安全的，使用dispatch_once确保只创建一个实例
 */
+ (instancetype)shareThinkingManager;

/**
 * @brief 获取DMThinkingManager单例实例（兼容性方法）
 *
 * @return DMThinkingManager的单例实例
 *
 * @note 该方法是shareThinkingManager的别名，提供与其他Manager一致的命名
 */
+ (instancetype)sharedManager;

#pragma mark - SDK配置

/**
 * @brief 配置和初始化ThinkingData SDK
 *
 * 该方法会执行以下配置：
 * - 设置时区校准
 * - 配置第三方数据共享
 * - 启用自动追踪功能
 * - 设置自定义库信息
 *
 * @note 建议在应用启动时调用此方法进行初始化
 */
- (void)thinkingConfig;

#pragma mark - 公共属性管理

/**
 * @brief 设置公共属性
 *
 * 公共属性会自动添加到后续所有事件中，适用于设置用户的持久化属性。
 *
 * @param jsonStr 公共属性数据，支持NSDictionary或JSON字符串格式
 *
 * @note 如果传入JSON字符串格式不正确，会记录错误日志但不会崩溃
 *
 * @example
 * ```objc
 * // 使用字典格式
 * [manager thinkingSetSuperPropertiesJsonStr:@{@"user_level": @"VIP", @"platform": @"iOS"}];
 *
 * // 使用JSON字符串格式
 * [manager thinkingSetSuperPropertiesJsonStr:@"{\"user_level\":\"VIP\",\"platform\":\"iOS\"}"];
 * ```
 */
- (void)thinkingSetSuperPropertiesJsonStr:(id)jsonStr;

#pragma mark - 事件追踪

/**
 * @brief 追踪自定义事件
 *
 * @param key 事件名称，不能为nil或空字符串
 * @param jsonStr 事件属性，支持NSDictionary或JSON字符串格式，不能为nil
 *
 * @note 如果参数无效或JSON解析失败，会记录错误日志
 *
 * @example
 * ```objc
 * // 追踪按钮点击事件
 * [manager thinkingTrackEventWithKey:@"button_click"
 *                            jsonStr:@{@"button_name": @"login", @"page": @"home"}];
 *
 * // 追踪购买事件
 * [manager thinkingTrackEventWithKey:@"purchase"
 *                            jsonStr:@"{\"product_id\":\"item_001\",\"amount\":9.99}"];
 * ```
 */
- (void)thinkingTrackEventWithKey:(NSString *)key jsonStr:(id)jsonStr;

/**
 * @brief 追踪自定义事件（兼容性方法）
 *
 * @param key 事件名称，不能为nil或空字符串
 * @param properties 事件属性，必须为NSDictionary格式，不能为nil
 *
 * @note 该方法是thinkingTrackEventWithKey:jsonStr:的别名，专门用于NSDictionary格式的属性
 */
- (void)thinkingTrackEventWithKey:(NSString *)key properties:(NSDictionary *)properties;

#pragma mark - 用户属性管理

/**
 * @brief 设置用户属性（支持 JSON / 字典）
 *
 * 设置用户的属性信息，如果属性已存在则会覆盖原值。
 *
 * @param jsonStr 用户属性，支持 NSDictionary 或 JSON 字符串
 *
 * @note 当传入 JSON 字符串格式不正确时会记录错误日志，不会抛出异常
 *
 * @example
 * ```objc
 * // 使用字典批量设置
 * [manager thinkingTrackUserPropertiesJsonStr:@{ @"user_name": @"张三", @"user_age": @"25" }];
 *
 * // 使用 JSON 字符串批量设置
 * [manager thinkingTrackUserPropertiesJsonStr:@"{\"user_name\":\"张三\",\"user_age\":\"25\"}"];
 * ```
 */
 - (void)thinkingTrackUserPropertiesJsonStr:(id)jsonStr;

/**
 * @brief 设置用户属性（仅首次设置有效）
 *
 * 设置用户属性，如果该属性之前已经设置过，则本次设置无效。
 * 适用于设置用户的固定属性，如首次注册时间、用户ID等。
 *
 * @param key 属性名称，不能为nil或空字符串
 * @param value 属性值，不能为nil
 *
 * @example
 * ```objc
 * [manager thinkingUser_setOnceWithKey:@"first_login_time" value:@"2025-01-07"];
 * [manager thinkingUser_setOnceWithKey:@"user_id" value:@"12345"];
 * ```
 */
- (void)thinkingUser_setOnceWithKey:(NSString *)key value:(NSString *)value;

#pragma mark - 游戏关卡事件追踪

/**
 * @brief 追踪关卡进入事件
 *
 * @param level 关卡等级，支持负数但会记录警告日志
 *
 * @note 实际追踪的关卡值会加上偏移量100000
 */
- (void)thinkingTrackLevelEnter:(NSInteger)level;

/**
 * @brief 追踪关卡开始事件
 *
 * @param level 关卡等级，支持负数但会记录警告日志
 *
 * @note 实际追踪的关卡值会加上偏移量100000
 */
- (void)thinkingTrackLevelStart:(NSInteger)level;

/**
 * @brief 追踪关卡胜利事件
 *
 * @param level 关卡等级，支持负数但会记录警告日志
 *
 * @note 实际追踪的关卡值会加上偏移量100000
 */
- (void)thinkingTrackLevelWin:(NSInteger)level;

/**
 * @brief 追踪关卡失败事件
 *
 * @param level 关卡等级，支持负数但会记录警告日志
 *
 * @note 实际追踪的关卡值会加上偏移量100000
 */
- (void)thinkingTrackLevelFail:(NSInteger)level;

/**
 * @brief 追踪关卡复活事件
 *
 * @param level 关卡等级，支持负数但会记录警告日志
 *
 * @note 实际追踪的关卡值会加上偏移量100000
 */
- (void)thinkingTrackLevelRevive:(NSInteger)level;

/**
 * @brief 追踪关卡重试事件
 *
 * @param level 关卡等级，支持负数但会记录警告日志
 *
 * @note 实际追踪的关卡值会加上偏移量100000
 */
- (void)thinkingTrackLevelRetry:(NSInteger)level;

/**
 * @brief 追踪关卡道具使用事件
 *
 * @param level 关卡等级，支持负数但会记录警告日志
 *
 * @note 实际追踪的关卡值会加上偏移量100000
 */
- (void)thinkingTrackLevelProp:(NSInteger)level;

@end

NS_ASSUME_NONNULL_END
